Wording fixes in documentation #1910
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #1910 +/- ##
==========================================
- Coverage 95.74% 95.70% -0.04%
==========================================
Files 29 29
Lines 7827 7827
Branches 1179 1179
==========================================
- Hits 7494 7491 -3
- Misses 192 194 +2
- Partials 141 142 +1 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
jmwright
reviewed
Nov 4, 2025
| While the first code style is what people default to, it's important to note that when you write your code like this it's equivalent as writting it on a single line. | ||
| It's then more difficult to debug as you cannot visualize each operation step by step, which is a functionality that is provided by the CQ-Editor debugger for example. | ||
| While the chained code style is succinct and intuitive and may be what people default to, it's important to note that all operations take place within a single statement (even if the code spans multiple lines). | ||
| This chained style be more difficult to debug using tools that allow a user to step statement-by-statement through the code (such as the CQ-Editor), because operations will occur simultaneously as part of a single statement. |
There was a problem hiding this comment.
Suggested change
| This chained style be more difficult to debug using tools that allow a user to step statement-by-statement through the code (such as the CQ-Editor), because operations will occur simultaneously as part of a single statement. | |
| This chained style can be more difficult to debug using tools that allow a user to step statement-by-statement through the code (such as the CQ-Editor), because operations will occur simultaneously as part of a single statement. |
jmwright
reviewed
Nov 4, 2025
| While the Fluent API exposes a lot of functionality, you may find scenarios that require extra flexibility or require working with lower level objects. | ||
|
|
||
| The direct API is the API that is called by the fluent API under the hood. The 9 topological classes and their methods compose the direct API. | ||
| The Direct API is the API that is called by the Fluent API under the hood. The 9 topological classes and their methods comprise the Direct API. |
There was a problem hiding this comment.
Did you want a newline between the sentences here too?
jmwright
reviewed
Nov 4, 2025
| The Direct API is the API that is called by the Fluent API under the hood. The 9 topological classes and their methods comprise the Direct API. | ||
| These classes actually wrap the equivalent Open CASCADE Technology (OCCT) classes. | ||
| The 9 topological classes are : | ||
| The 9 topological classes are: |
There was a problem hiding this comment.
Perhaps an extra newline above this line so that it starts a new paragraph?
jmwright
reviewed
Nov 4, 2025
| Each class has its own methods to create and/or edit shapes of their respective type. | ||
| One can also use the :doc:`free-func` to create and modify shapes. | ||
| As already explained in :ref:`cadquery_concepts` there is a hierarchy when composing geometry from topological classes: | ||
| a :class:`~cadquery.Wire` is made of several :class:`~cadquery.Edge`s which are themselves made of several :class:`~cadquery.Vertex`es. |
There was a problem hiding this comment.
These class embeds are not rendering correctly in the finished document.
jmwright
reviewed
Nov 4, 2025
| This means you can create geometry starting at the lowest level of this hierarchy and exert exact control over t. | ||
| For example we can create a circular face like so :: | ||
| For example we can create a circular face by first creating a list of :class:`~cadquery.Wire`s that form the circle as follows: :: |
There was a problem hiding this comment.
Same class embed rendering issue here.
jmwright
reviewed
Nov 4, 2025
| The Direct API is so named because each method call directly returns an object of the specified topological type. | ||
| Functions in the Direct API do not provide a parent/children data structure that can be traversed with function call chaining. | ||
| The Direct API is more verbose than the Fluent API and more tedious to work with, but as it offers more flexibility it is sometimes more convenient or capable than the Fluent API. | ||
| (For example, you can work with faces in the Direct API, which is something you can't do in the Fluent API.) |
There was a problem hiding this comment.
I don't understand this statement. Faces are accessible at the fluent API level.
jmwright
reviewed
Nov 4, 2025
| OCP provides access to (almost) all the OCCT C++ libraries in Python and in CadQuery. | ||
| Working with the OCCT API will give you the maximum flexibility and control over you designs, but is very verbose and difficult to use. | ||
| You will need to have a strong working knowledge of the underlying OCCT C++ libraries to use the Direct API in CadQuery. | ||
| The most useful references for this purpose are: |
There was a problem hiding this comment.
Maybe an extra newline above this line?
jmwright
reviewed
Nov 4, 2025
|
|
||
| The package name of any class is written at the top of the documentation page. Often it's written in the class name itself as a prefix. | ||
| The package name of any class is written at the top of its documentation page. | ||
| The package name is also often written in the class name itself as a prefix. |
There was a problem hiding this comment.
Some repetition has been added in a few places like this: "The package name" being used twice.
|
Thanks @alhirzel I left comments. @adam-urbanczyk @lorenzncode The Codecov fail is for an indirect change on a code file that was not altered. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.